Object handling

Once you have created your application, with windows as children, and you have defined the contents of any windows, you are ready to open them and handle your world.

It is the case to remember that:

The first operation is to set all the notifications that will occurs.

Any attributes of type N of an object can be used to take care of events.

E.g. if you have a menu item AboutMUI that has only to open the MUI about requester, all you have to do is set up a notification on that event via the call

   call Notify("AboutMUI","MENUTRIGGER","EVERYTIME","APP","ABOUTMUI","WIN")

Remember that the more notifications among objects you set up the less you have to care about your work.

Obviously, there are events that must be handled by yourself in the main handle cycle.

If you want an object to just return its name when an attribute of it changes, you must do

   call Notify(obj,attr,value,app,"RETURNID") 

E.g.

   call Notify("BUTTON","PRESSED",0,"APP","RETURNID") 

As you can see, events to be dispatched by yourself are always notified to an application objects.

An application objects accepts the following methods to handle events that may occur on objects:

• RETURNID [QUIET]
• RETURN <string> [attr]
• INLINE <fun> [attr]
• SETVAR [var]

RETURNID

is used when you only want the application to return you the name of the object; the special parameter QUIT means that the triggering event is a application killer one

   call Notify("win","CLOSEREQUEST",1,"app","RETURNID","QUIT")

RETURN

is used when you want to return custom strings to the application (with len <=64 chars) and when you want to read the value of the triggering attribute any time it changes

   call Notify("cycle","active","everytime","app","return","CYCLE","TRIGGERATTR")

It accept any G attribute as second parameter plus the special string TRIGGERATTR that means the same attribute that triggers the notification.

INLINE

Used in notification such as:

    call Notify("slider",trigger,value,"app","InLine","parse arg name,value;...",attr)

When trigger changes to value, fun, an inline ARexx function macro, is called with arguments:

1. the name of the notifier object
2. the value of attr; the attribute must be G; a special value is TRIGGERATTR that means the triggering attribute; if no attribute is supplied, the function receives just one argument.

The function is called in the same process of the running macro and so in it there can be used any RxMUI functions on any object, but it is called as a separate ARexx macro and HASN'T GOT the environment of the running macro (e.g. ala INTEPRET command). It means mainly that the existing variables are not valid in the function (they just don't exist).

SETVAR

is used when you want to set a variable to the value of the attribute that triggers the notification

   call Notify("cycle","active","everytime","app","SET","CYCLEACTIVE")   

Classes may define their own methods to return events.

After that, you enter in the main cycle, THAT IS:

   ctrl_c=2**12
    do forever
        call NewHandle("APP","H",ctrl_c)
        if and(h.signals,ctrl_c)~=0 then exit /* user break */
        select
            when h.event="QUIT" then exit /* quit event */
            when h.event=...
            ...
        end
    end

When you receive a QUIT you must exit. If you have to complete other operations before exiting, you should get the attribute FORCEQUIT of the application to see if you can loose time.

In h.event there will be the name of the object that triggered the event via RETURNID or the string you set up via RETURN In the case of e.g.

   call Notify("cycle","active","everytime","app","return","CYCLE","TRIGGERATTR")

you will have in h.active the active entry of CYCLE.

If you set up a SETVAR notification, nothing is returned, but you can be sure that in the specified var there is the value you need.

RxMUI may receive 3 special events:

• APPEVENT
• DROPEVENT
• AREXXCMD

APPEVENT

after you have declared a window APPWINDOW with that attribute set to 1, you will receive a APPEVENT anytime an icon is dropped into the window or into any object of the window, you have previously enabled to receive dropped icon via AppMessage() . You will find the name of the object in h.to and the complete path to the icon in h.name

DROPEVENT

user Drag & Drop: a "manual drag and drop" must be performed. The interested objects are in h.from and h.to .

AREXXCMD

You set WantARexxCmd at Application Init time and an ARexx command unknown to MUI comes to the Application ARexx port. Anytime someone sends a message to the Application ARexx port and MUI doesn't know what to do with this command, it is notified to the Application via this event. Note that at this time, the message is already replied and you can't set any return code or result to send back.

Similar to NewHandle() is Handle(). The differences are:

1. NewHandle() just returns ONE event;
   Handle() may returns one or MORE events
2. NewHandle() waits for signals internally;
   Handle() doen't wiat for signal and you have to wait for them manually in the macro, e.g. via rmh.library/wait()

So the default cycle using Handle() is:

   ctrl_c=2**12
    s=0
    do forever
        call Handle("APP","H",s)
        do i=0 to h.num-1
            if h.i="QUIT" then exit /* quit event */
            if h.i==... then
            ...
        end
        s=Wait(or(h.signals,ctrl_c))
        if and(s,ctrl_c)~=0 then exit /* user break */
    end

Or if you manage any kind of manual drag and drop:

   ctrl_c=2**12
    s=0
    do forever
        ws=1
        call handle("APP","H",s)
        do i=0 to h.num-1
            if h.i="QUIT" then exit /* quit event */
            if h.i=="DROPEVENT" then do
                /* handle drag and drop from h.i.from to h.i.to */
                ws=0
            end
            if h.i==... then
            ...
        end
        if ~ws then iterate
        s=Wait(or(h.signals,ctrl_c))
        if and(s,ctrl_c)~=0 then exit /* user break */
    end

Handle() should be used only in peculiar situations, when you really have to wait for signals in the macro, e.g. you have to wait for non-blocking sockets events via rxsocket.library/WaitSelect(). In ordinary situations you should always use NewHandle().

So the event you may receive are: